home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / GetBitmap.3 < prev    next >
Text File  |  1995-07-21  |  12KB  |  421 lines
  1. '\"
  2. '\" Copyright (c) 1990 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/GetBitmap.3,v 1.11 93/04/01 09:41:24 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tk_GetBitmap tkc
  206. .BS
  207. .SH NAME
  208. Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tk.h>\fR
  212. .sp
  213. Pixmap
  214. \fBTk_GetBitmap(\fIinterp, tkwin, id\fB)\fR
  215. .sp
  216. .VS
  217. int
  218. \fBTk_DefineBitmap(\fIinterp, nameId, source, width, height\fR)\fR
  219. .VE
  220. .sp
  221. Tk_Uid
  222. .VS
  223. \fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR
  224. .sp
  225. \fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR
  226. .sp
  227. \fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR
  228. .VE
  229. .SH ARGUMENTS
  230. .AS "unsigned long" *pixelPtr
  231. .AP Tcl_Interp *interp in
  232. Interpreter to use for error reporting.
  233. .AP Tk_Window tkwin in
  234. Token for window in which the bitmap will be used.
  235. .AP Tk_Uid id in
  236. Description of bitmap;  see below for possible values.
  237. .AP Tk_Uid *nameId in
  238. Name for new bitmap to be defined.
  239. .AP char *source in
  240. Data for bitmap, in standard bitmap format.
  241. Must be stored in static memory whose value will never change.
  242. .AP "unsigned int" width in
  243. Width of bitmap.
  244. .AP "unsigned int" height in
  245. Height of bitmap.
  246. .AP "unsigned int" *widthPtr out
  247. Pointer to word to fill in with \fIbitmap\fR's width.
  248. .AP "unsigned int" *heightPtr out
  249. Pointer to word to fill in with \fIbitmap\fR's height.
  250. .AP Display *display in
  251. Display for which \fIbitmap\fR was allocated.
  252. .VS
  253. .VE
  254. .AP Pixmap bitmap in
  255. Identifier for a bitmap allocated by \fBTk_GetBitmap\fR.
  256. .BE
  257.  
  258. .SH DESCRIPTION
  259. .PP
  260. These procedures manage a collection of bitmaps (one-plane pixmaps)
  261. being used by an application.  The procedures allow bitmaps to be
  262. re-used efficiently, thereby avoiding server overhead, and also
  263. allow bitmaps to be named with character strings.
  264. .PP
  265. \fBTk_GetBitmap\fR takes as argument a Tk_Uid describing a bitmap.
  266. It returns a Pixmap identifier for a bitmap corresponding to the
  267. description.  It re-uses an existing bitmap, if possible, and
  268. creates a new one otherwise.  At present, \fIid\fR must have
  269. one of the following forms:
  270. .TP 20
  271. \fB@\fIfileName\fR
  272. \fIFileName\fR must be the name of a file containing a bitmap
  273. description in the standard X11 or X10 format.
  274. .TP 20
  275. \fIname\fR
  276. \fIName\fR must be the name of a bitmap defined previously with
  277. a call to \fBTk_DefineBitmap\fR.  The following names are pre-defined
  278. by Tk:
  279. .RS
  280. .TP 12
  281. \fBerror\fR
  282. .VS
  283. The international "don't" symbol:  a circle with a diagonal line
  284. across it.
  285. .VE
  286. .TP 12
  287. \fBgray50\fR
  288. 50% gray: a checkerboard pattern where every other bit is on.
  289. .TP 12
  290. \fBgray25\fR
  291. 25% gray: a pattern where 25% of the bits are on, consisting of all the
  292. bit positions that can be reached by a chess knight starting at (0,0).
  293. .TP 12
  294. \fBhourglass\fR
  295. .VS
  296. An hourglass symbol.
  297. .TP 12
  298. \fBinfo\fR
  299. A large letter ``i''.
  300. .TP 12
  301. \fBquesthead\fR
  302. The silhouette of a human head, with a question mark in it.
  303. .TP 12
  304. \fBquestion\fR
  305. A large question-mark.
  306. .TP 12
  307. \fBwarning\fR
  308. A large exclamation point.
  309. .VE
  310. \fB
  311. .RE
  312. .LP
  313. Under normal conditions, \fBTk_GetBitmap\fR
  314. returns an identifier for the requested bitmap.  If an error
  315. occurs in creating the bitmap, such as when \fIid\fR refers
  316. to a non-existent file, then \fBNone\fR is returned and an error
  317. message is left in \fIinterp->result\fR.
  318. .PP
  319. \fBTk_DefineBitmap\fR associates a name with
  320. .VS
  321. in-memory bitmap data so that the name can be used in later
  322. calls to \fBTk_GetBitmap\fR.  The \fInameId\fR
  323. argument gives a name for the bitmap;  it must not previously
  324. have been used in a call to \fBTk_DefineBitmap\fR.
  325. The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR
  326. describe the bitmap.
  327. \fBTk_DefineBitmap\fR normally returns TCL_OK;  if an error occurs
  328. (e.g. a bitmap named \fInameId\fR has already been defined) then
  329. TCL_ERROR is returned and an error message is left in
  330. \fIinterp->result\fR.
  331. Note:  \fBTk_DefineBitmap\fR expects the memory pointed to by
  332. \fIsource\fR to be static:  \fBTk_DefineBitmap\fR doesn't make
  333. a private copy of this memory, but uses the bytes pointed to
  334. by \fIsource\fR later in calls to \fBTk_GetBitmap\fR.
  335. .VE
  336. .PP
  337. Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a
  338. bitmap file directly into a C program and then referencing
  339. the variables defined by the file.
  340. For example, suppose there exists a file \fBstip.bitmap\fR,
  341. which was created by the \fBbitmap\fR program and contains
  342. a stipple pattern.
  343. The following code uses \fBTk_DefineBitmap\fR to define a
  344. new bitmap named \fBfoo\fR:
  345. .nf
  346. .RS
  347. \fCPixmap bitmap;
  348. #include "stip.bitmap"
  349. Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,
  350.     stip_width, stip_height);
  351. \&...
  352. bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));\fR
  353. .RE
  354. .fi
  355. This code causes the bitmap file to be read
  356. at compile-time and incorporates the bitmap information into
  357. the program's executable image.  The same bitmap file could be
  358. read at run-time using \fBTk_GetBitmap\fR:
  359. .nf
  360. .RS
  361. \fCPixmap bitmap;
  362. bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap"));\fR
  363. .RE
  364. .fi
  365. The second form is a bit more flexible (the file could be modified
  366. after the program has been compiled, or a different string could be
  367. provided to read a different file), but it is a little slower and
  368. requires the bitmap file to exist separately from the program.
  369. .PP
  370. \fBTk_GetBitmap\fR maintains a
  371. database of all the bitmaps that have been created.
  372. Whenever possible, it will return an existing bitmap rather
  373. than creating a new one.
  374. This approach can substantially reduce server overhead, so
  375. \fBTk_GetBitmap\fR should generally be used in preference to Xlib
  376. procedures like \fBXReadBitmapFile\fR.
  377. .PP
  378. The bitmaps returned by \fBTk_GetBitmap\fR
  379. are shared, so callers should never modify them.
  380. If a bitmap must be modified dynamically, then it should be
  381. created by calling Xlib procedures such as \fBXReadBitmapFile\fR
  382. or \fBXCreatePixmap\fR directly.
  383. .PP
  384. The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of
  385. \fBTk_GetBitmap\fR.
  386. Given an X Pixmap argument, it returns the \fIid\fR that was
  387. passed to \fBTk_GetBitmap\fR when the bitmap was created.
  388. .VS
  389. \fIBitmap\fR must have been the return value from a previous
  390. call to \fBTk_GetBitmap\fR.
  391. .VE
  392. .PP
  393. \fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR
  394. .VS
  395. argument in the words pointed to by the \fIwidthPtr\fR and
  396. \fIheightPtr\fR arguments.  As with \fBTk_NameOfBitmap\fR,
  397. \fIbitmap\fR must have been created by \fBTk_GetBitmap\fR.
  398. .VE
  399. .PP
  400. When a bitmap returned by \fBTk_GetBitmap\fR
  401. is no longer needed, \fBTk_FreeBitmap\fR should be called to release it.
  402. There should be exactly one call to \fBTk_FreeBitmap\fR for
  403. each call to \fBTk_GetBitmap\fR.
  404. When a bitmap is no longer in use anywhere (i.e. it has been freed as
  405. many times as it has been gotten) \fBTk_FreeBitmap\fR will release
  406. it to the X server and delete it from the database.
  407.  
  408. .SH BUGS
  409. In determining whether an existing bitmap can be used to satisfy
  410. a new request, \fBTk_GetBitmap\fR
  411. considers only the immediate value of its \fIid\fR argument.  For
  412. example, when a file name is passed to \fBTk_GetBitmap\fR,
  413. \fBTk_GetBitmap\fR will assume it is safe to re-use an existing
  414. bitmap created from the same file name:  it will not check to
  415. see whether the file itself has changed, or whether the current
  416. directory has changed, thereby causing the name to refer to
  417. a different file.
  418.  
  419. .SH KEYWORDS
  420. bitmap, pixmap
  421.